Express Compression JPEG Application Program Interface (ECJAPI) (c) 1993,1994 Expressed Compression Laboratories ******************************************************************************** ECJ_Decode (2.x) -------------------------------------------------------------------------------- #include "ecjapi.h" HANDLE ECJ_Decode( lpstrfilename, wParam, lParam, lpfnECJ_CallBack ) LPSTR lpstrFileName; /* name of file to decode */ WORD wParam; /* attributes */ LONG lParam; /* optional parameters */ ECJCB lpfnECJ_CallBack; /* call back routine */ ECJ_Decode decodes the specified JPEG file and returns a device independent bitmap (DIB). Parameter Description --------------------------------------------------------------------------- lpstrFileName Points to a null-terminated string that names the JPEG file to be decoded. wParam Specifies how decoding shall proceed. This parameter can be a combination of the following values. Value Meaning -------------- ------------------------------------------- ECJ_GRAY_ONLY Create a gray only DIB. ECJ_24_BITS Create a 24 bit DIB. ECJ_2_PASS Use two-pass 24 to 8 bit colour quantisation. ECJ_DITHER Use FS dithering in 2-pass color quantisation. ECJ_HALF_SIZE Shrink the dimensions of the picture by half. ECJ_4_SIZE Shrink the dimensions of the picture by 1/4th. ECJ_8_SIZE Shrink the dimensions of the picture by 1/8th. ECJ_AUTO_SIZE Automatically shrink the dimensions of the picture when appropriate. ECJ_DITHER can only be used in conjunction with ECJ_2_PASS. ECJ_GRAY_ONLY, ECJ_24_BITS and ECJ_2_PASS are mutually exclusive. ECJ_HALF_SIZE, ECJ_4_SIZE and ECJ_8_SIZE are mutually exclusive, while ECJ_AUTO_SIZE takes precedence over all of them. By default (with wParam = 0) ECJ_Decode creates an 8 bit DIB, using single pass colour quantisation with ordered dithering when appropriate. lParam Bits 24 to 30 can be used as an optional 7 bit label, which is passed back to the client during callback, for the purpose of uniquely identifying each call to ECJ_Decode when multiple calls are made in parallel. lpfnECJ_CallBack Specifies the procedure-instance address of the callback procedure. ECJ_Decode sends messages and periodically passes control back to the client via the ECJ callback procedure. Setting this parameter to NULL disables the callback mechanism. For more information see the description of the ECJ_CallBack function. Returns ======= The return value is the handle to the DIB if the function is successful. Otherwise, it is NULL. See Also ======== ECJ_CallBack ******************************************************************************** ECJ_DecodeMem (2.x) -------------------------------------------------------------------------------- #include "ecjapi.h" HANDLE ECJ_DecodeMem( hStream, dwStreamLen, wParam, lParam, lpfnECJ_CallBack ) HGLOBAL hStream; /* handle to bitstream in memory */ DWORD dwStreamLen; /* size of bitstream in bytes */ WORD wParam; /* attributes */ LONG lParam; /* optional parameters */ ECJCB lpfnECJ_CallBack; /* call back routine */ ECJ_DecodeMem decodes the specified JPEG file and returns a device independent bitmap (DIB). ECJ_DecodeMem is essentially the same as ECJ_Decode, except that instead of taking a filename it takes a memory object as input. Parameter Description --------------------------------------------------------------------------- hStream Global handle to memory object containing bitstream to be decoded. dwStreamLen Size of the bitstream in bytes. See ECJ_Decode for explanations on the rest of the parameters. ******************************************************************************** ECJ_Crop (2.x) -------------------------------------------------------------------------------- #include "ecjapi.h" HANDLE ECJ_Crop ( lpstrInFileName, hInStream, lParam, dwInStreamLen, lprectCropRect, lpstrOutFileName, lpdwOutStreamLen, lpfnECJ_CallBack ) LPSTR lpstrInFileName; /* name of the source file */ HANDLE hInStream; /* handle to input bitstream in memory */ DWORD dwInStreamLen; /* size of input bitstream in bytes */ LONG lParam; /* optional parameter */ LPRECT lprectCropRect; /* cropping rectangle */ LPSTR lpstrOutFileName; /* name of output file */ LPDWORD lpdwOutStreamLen; /* length of output bitstream */ ECJCB lpfnECJ_CallBack; /* call back routine */ ECJ_Crop creats a windowed version of the input JPEG image, in accordance with the specfied cropping rectangle. This is achieved by direct manipulation of the input bitstream in the DCT domain, and no additional distortion is introduced in the process. The input bitstream is contained either in a source file or in a memory object. The output bitstream can be written directly to a specified file, or can be returned as a memory object. Parameter Description --------------------------------------------------------------------------- lpstrInFileName Points to a null-terminated string that names the source JPEG file. It should be NULL if the input is contained in a memory object. hInStream Global handle to memory object containing the source JPEG bitstream. It should be NULL if the input is contained in a file. lParam Bits 24 to 30 can be used as an optional 7 bit label, which is passed back to the client during callback, for the purpose of uniquely identifying each call to ECJ_Decode when multiple calls are made in parallel. dwInStreamLen Indicates the size of the bitstream in bytes if the input is to be taken from memory. lprectCropRect The cropping rectangle. lprectCropRect.left specifies the number of columns, in units of 8, that should be removed from the left of the picture. lprectCropRect.right specifies the number of columns, in units of 8, that should be removed from the right edge of the picture. lprectCropRect.top and lprectCropRect.right have similar semantics. For 411 format images, all members should have even values. The minimum cropping unit is this case is 16x16. For 422 format images, the left and right members should have even values, in which case the minimum cropping unit is 16x8. A value supplied as odd which should have been even will be truncated, with 1 subtracted from it. lpstrOutFileName Points to a null-terminated string that names the output JPEG file. It should be NULL if the output is to be returned as a memory object. lpdwOutStreamLen Returns the size of the output bitstream in bytes if the output is to be returned as a memory object. lpfnECJ_CallBack Specifies the procedure-instance address of the callback procedure. See ECJ_Decode and ECJ_CallBack. Returns ======= If lpstrOutFileName is NULL, a handle to the memory object containing the output JPEG bitstream is returned upon successful completion. If the output is to be written to a file, an arbitrary, non-NULL value is returned. In both cases NULL is returned if the operation fails. See Also ======== ECJ_Decode, ECJ_CallBack ******************************************************************************** ECJ_CallBack (2.x) -------------------------------------------------------------------------------- #include "ecjapi.h" int CALLBACK ECJ_CallBack( mMsg, wParam, lParam ) WORD mMsg; /* message */ WORD wParam; /* first message parameter */ LONG lParam; /* second message parameter */ The ECJ_CallBack function is an application-defined callback function that processes messages sent by ECJ_Decode. Parameter Description -------------------------------------------------------------------------- mMsg Specifies the message. Message Meaning ----------------------------------------------------------- ECJ_RESOLUTION Upon decoding the header of the image ECJ_Decode returns with the following information: Parameter Bits Meaning ------------------------------------------- lParam 0-15 Vertical dimension. lParam 15-32 Horizontal dimension. wParam 0-2 Video format. 0 = Y; 1 = YUV422; 2 = YUV411; 3 = YUV444; wParam 3 Picture shrunk by half. wParam 4 Picture shrunk by 1/4th. wParam 5 Picture shrunk by 1/8th. ECJ_PROGRESS ECJ_Decode periodically returns control to the client with progress information: wParam Stage ------ ---------------------------------- 0 Pass 1 1 Creating histogram 2 Pass 2 For stages 0 and 2, lParam indicates percentage completion. ECJ_ERROR An error has occured. wParam identifies the particular error. wParam Error --------------------------------------------- 1 File is not JPEG. 2 Can't open file. 3 Unexpected EOF. 4 Out of memory. 5 Unrecognised video format. 6 Unexpected scan component. 7 Unexpected marker. 8 Unexpected RST. 9 Unsupported precision. 10 User abort. wParam Bits 8-14 contains the optional 7 bit label passed to the DLL. The remaining bits contain message-dependent information. lParam More message-dependent information. Returns ======= To continue decoding a value of 0 shall be returned. A return value of -1 instructs ECJ_Decode to abort decoding immediately. Comments ======== The client does not have to process any of the messages. The simplest ECJ_CallBack function can simply return 0. A more well behaved application should take the opportunity to momentarily pass control back to Windows to achieve non-preemptive multitasking. See Also ======== ECJ_Decode ******************************************************************************** ECJ_Info (2.x) -------------------------------------------------------------------------------- #include "ecjapi.h" int ECJ_Info( lpstrfilename, lpX, lpY, lpColourFormat ) LPSTR lpstrFileName; /* name of JPEG file */ LPINT lpX; /* horizontal size */ LPINT lpY; /* vertical size */ LPINT lpVideoFormat; /* video format */ ECJ_Info provides some basic information on the specified JPEG file, which would otherwise be unavailable when the CallBack mechanism is not used. In particular the video format information is useful in determining the minimum cropping units. Parameter Description --------------------------------------------------------------------------- lpstrFileName Points to a null-terminated string that names the JPEG file. lpX Pointer to integer which contains the horizontal size of the picture upon successful return. lpY Pointer to integer which contains the vertical size of the picture upon successful return. lpVideoFormat Pointer to integer which contains the chroma-subsampling format of the picture. 0 = Y; 1 = YUV422; 2 = YUV411; 3 = YUV444; Returns ======= Returns 0 if the function is successful. See Also ======== ECJ_InfoMem, ECJ_CallBack, ECJ_Crop ******************************************************************************** ECJ_InfoMem (2.x) -------------------------------------------------------------------------------- int ECJ_Info( hStream, dwStreamLen, lpX, lpY, lpColourFormat ) HGLOBAL hStream; /* handle to bitstream in memory */ DWORD dwStreamLen; /* size of bitstream in bytes */ LPINT lpX; /* horizontal size */ LPINT lpY; /* vertical size */ LPINT lpVideoFormat; /* video format */ ECJ_InfoMem provides some basic information on the specified JPEG bitstream. ECJ_InfoMem is essentially the same as ECJ_Info, except that instead of taking a filename it takes a memory object as input. Parameter Description --------------------------------------------------------------------------- hStream Global handle to memory object containing bitstream. dwStreamLen Size of the bitstream in bytes. See ECJ_Info for explanations on the rest of the parameters. Returns ======= Returns 0 if the function is successful. See Also ======== ECJ_Info, ECJ_CallBack, ECJ_Crop